In this Chapter:
- Configuring Signup Forms using the default templates.
- Configuring Custom Forms.
- Setting up Email Notifications and SalesForce integration.
- Customizing the user experience using SML's Javascript hooks.
- Validation and custom error messaging through javascript.
Chapter 5: All About Forms
This chapter covers the development of an application which collects signup data through a form, available for later export by admins.
The walk through builds on Chapter 3 - it assumes you are familiar with feature blocks and using their built-in JavaScript helper functions.
After completing this chapter you'll be able to add complex sign up forms to your applications.
This chapter is an example of using a signup form to collect entries for a sweepstakes. Let's get started!
Basic Form Template
- In your SML application, type the following code:
{% signup_form %}{% endsignup_form %}
Then click "Save".
First you'll notice a new Feature Block, signup_form. This feature allows you to easily collect information from users through a form. The data is collected, hosted and available for export at any time by an administrator. More on this export functionality later. We do not currently support automated syncing with an external database.
As with the rss_feed - and most other feature blocks - dropping in just the start and end tags of the signup_form feature block gives a user experience that's very close to the standalone app. You can build out a completely functional form with basic field-requirement validation from the configuration menu and - since we're using the configuration menu and not code - that form can be edited by a brand manager or other non-technical person. You can even use CSS to overwrite the default styles and customize appearance, to a certain extent at least.
Let's go ahead and work our way through the configuration and come back to the code in a minute.
Configuring Export
Our system will save all submitted form data forever - until and unless you use the link in your configuration window to manually delete it. You can export signup data directly from the settings page. For each input that you wish to export, you'll need to add a reporting field under the reporting section. Fields can be added and removed from this section at any time - changes only affect which fields are displayed in the report. If you're using the default signup form interface adding fields here will also make them appear on your tab. If you customize your code, however, the fields in the reporting section simply map the data to export.
Once your reporting fields have been configured, you can export collected signups by clicking the download signups link at any point.
Configuring Email Notifications
Along with self-serve export, you can also configure your form to notify any email address whenever a new signup is collected. A common use case for email notifications is simple integration with third-party systems. Any system that can receive mail can integrate with your signup form!
Here is an example of the email:
The campaign owner for <Campaign> SML (CampaignID: 169662), <User> (UserID: 1234567), has sent a new signup feature notification. Params: feature_id = 654321 page_id = 16248095488 email = hi@hi.com
Custom Configuration
Now that we have configuration sorted out, let's dive into the custom configuration options available with this feature block. Let's start by building out a basic form.
<h2>AwesomeBand's Concert Ticket Sweepstakes!</h2> <p>Enter now to win front-row tickets to AwesomeBand's next show!</p> {% signup_form %} <p> <label for="name">Name:</label> <input type="text" name="name"id="name"> </p> <p> <label for="email">Email:</label> <input type="text" name="email" id="email"> </p> <p> <label for="phone_no">Phone Number:</label> <input type="text" name="phone_no" id="phone_no"> </p> <p>{% signup_form_submit %}</p> {% endsignup_form %}
- With just a few lines of markup we now have a fully functioning signup form! Lets take a minute to break down the code. If the code here looks familiar it's because it should - the signup_form accepts all the standard html form fields and attributes and in fact renders as an HTML form on the live tab. Anything you can do in an HTML form you can do here. The feature block just gives you some tools for rapid configuration.
Using JavaScript to Customize User Experience
By default, a standard message is displayed after a user successfully submits their information but the form remains visible on the page. Often, designers will want to customize this success message. In this example, we'll mash the signup_form block together with a coupon block so that it shows the latest coupon to users who successfully submit the form.
We can create this experience by using the onsucess attribute to run a javascript function when the form is successfully submitted. We'll use JQuery to hide a new div that wraps around the form and then show our thank you message and coupon instead.
- Change your code to now read:
{% signup_form onsuccess:"customMessage();" %} <div class="form_body"> <p> <label for="name">Name:</label> <input type="text" name="name"> </p> <p> <label for="email">Email:</label> <input type="text" name="email"> </p> <p> <label for="phone_no">Phone Number:</label> <input type="text" name="phone_no"> </p> <p>{% signup_form_submit %}</p> </div> {% endsignup_form %} <div class="thanks" style="display:none;"> <h3> Thanks for signing up!</h3> <p>take advantage of this awesome coupon</p> {% coupon name:"march_regional" %} <a href="{{coupon.coupon_items.first.destination_url}}"> {{coupon.coupon_items.first.image_url | img_tag}} </a> {% endcoupon %} </div> <script type="text/javascript"> function customMessage() { $(".form_body").hide('fast'); $(".thanks").show('slow'); } </script>
- Click "Saves Changes" and "Return to Facebook Page". You should now see your custom success message.
As you can see, the onsucess hook is a powerful tool for customizing the user experience. You could also use the onerror trigger to trigger some function in the event of an error of some kind or create a custom submit button by replacing {% signup_form_submit %} with an editable image or text anchor that uses the do_submit tag to insert the javascript that triggers the signup_form feature block, like so:
{% editable_image name:"my_button" onclick:do_submit %}
or
<a href="#" onclick="{{ do_submit }}" class="my_button">Some text for a button</a>
Customizing the button this way allows us to potentially stack multiple functions onto our submission click, for instance you might want to call the Facebook OpenGraph and request user information to populate hidden fields in your form with information about the user from the graph. The Q&A Application in the sample code library has a good example of this technique in action.
Adding Validation
A common concern when dealing with forms is ensuring valid user input. Some fields may be mandatory while others must match valid formats. In our Sweepstakes, for example, we probably want to ensure that all fields are filled out by the user & that we are collecting valid e-mail addresses.
- Lets add some validations to our form.
- Update your code to now read:
{% signup_form onsuccess:"customMessage();" rules_var:"sweeprules" %}
<div id="signup_div">
<p>
<label for="name">Name:</label>
<input type="text" name="name">
</p>
<p>
<label for="email">Email:</label>
<input type="text" name="email">
</p>
<p>
<label for="phone_no">Phone Number:</label>
<input type="text" name="phone_no">
</p>
<p><button onclick="{{do_submit}}">Enter Now!</button></p>
</div>
{% endsignup_form %}
<div class="thanks" style="display:none;">
<h3> Thanks for signing up!</h3>
<p>take advantage of this awesome coupon</p>
{% coupon name:"march_regional" %}
<a href="{{coupon.coupon_items.first.destination_url}}">
{{coupon.coupon_items.first.image_url | img_tag}}
</a>
{% endcoupon %}
</div>
<script>
var sweeprules = {
email: {required: true,email: true},
name: {required: true},
phone_no: {required: true}
}
function customMessage() {
$(".form_body").hide('fast');
$(".thanks").show('slow');
}
</script>
- Click "Saves Changes" and "Return to Facebook Page". Now try submitting the form without all fields filled in or without a properly formatted email address. You should be prompted with an error message.
- How did the signup_form know to validate the form per our validation logic? To understand this, lets look closer at our changes...
We added a new JavaScript variable to our template called sweepRules. This object is a simple JavaScript hash. For each field in our form, we have a corresponding property in the hash. Each property then declares if it is required or needs to be validated.
The signup_form Feature Block has an additional attribute which takes the name of a variable with the same structure as our sweepsVar. When the form is submitted, the feature block validates the fields against this special JavaScript rules variable.
Validation in SML signup forms is simple yet very powerful - you can choose from several built-in validations or define your own custom validation logic by declaring your validations in a JavaScript variable.
